row/H3-NVFP4-STREAM-DIFF: the #94 NVFP4 ref2va-grid residual DIAGNOSED — no discrete load-path defect - #95

…quant fidelity (#95)

row/H3-NVFP4-STREAM-DIFF squash. Identical-weights activation diff:
divergence enters at the token refiner and amplifies chaotically, but
the guilty-class audit finds NO loader bug — every tensor class loads
quant-noise-close to the coherent GGUF, RoPE byte-identical, no
scramble/transpose/stride/dtype defect; both arms run identical code.
The grid is the community NVFP4 file's own quantization fidelity (corr
0.85-0.94, same converter lineage as the #94 nibble bug) times the
DiT's massive-activation sensitivity. Path forward: an official
modelopt-NVFP4 checkpoint, not a loader change. #94 nibble fix stands;
the fp4-resident Marlin arm grid stays the named wiring residual. The
byte-inert VT_H3_ACT_DUMP fingerprint hook ships as a permanent
instrument. Merge also anchors a parallel session's anchorless
startup-latency state entry.

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Code:claude-opus-4-8 [ClaudeCode]

…rds, 66.3 GB (#98)

Branch: row/H3-BF16-SHARDED-DIT (helper; CPU-only, no GPU job, no download).
Written 2026-08-06 off 075b9f2, REBASED onto f34e0d1 and re-gated before
landing; every number below is the POST-REBASE re-run, not the earlier report.

Every H3 render so far used a QUANTIZED DiT, and H3 is unusually
quantization-sensitive: Q3_K_M -> Q4_K_M alone turned a murky lattice-covered
silhouette into a photoreal close-up (ComfyUI PR 15298 attributes it to the
partial split-half RoPE producing channel-wise magnitude outliers that corrupt
even INT8). "What does FULL PRECISION look like?" could not be asked, because
every DiT loader took a SINGLE file while the bf16 release ships 13 safetensors
shards totalling 66.3 GB.

This is the CHECKPOINT half. The device streamer the real 66.3 GB load needs is
the stacked follow-up row/H3-BF16-SHARDED-STREAM, split out so each PR stays
inside the 900-line review cap.

- MiniMaxH3ShardedCheckpoint::Open(dir) (new minimax_h3_sharded.cpp) resolves
  tensors through the checkpoint's own model.safetensors.index.json weight map,
  never by scanning, with one index over every shard — the shape of the in-tree
  template LoadMiniMaxH3EncoderWeights(const std::vector<SafetensorsFile>&, ...).
  A tensor the index NAMES but whose shard does not contain it throws BY NAME;
  skipping it would read as zeros and render.
- EnumerateMiniMaxH3ShardedTensors builds the same names+shapes manifest the
  GGUF and NVFP4 arms build, so ParseMiniMaxH3DitParamsFromGgufManifest derives
  the geometry from SHAPES ALONE on a sharded checkpoint too.
- LoadMiniMaxH3DitFromShards is the host-f32 REFERENCE loader (comparison
  baseline and the CPU path for reduced checkpoints; ~132 GB on the real
  release, so not for real runs), and MiniMaxH3IsFp32IslandTensor single-sources
  the upstream fp32-ISLAND split the three existing streamers each hand-rolled.
- examples/minimax_h3_gen accepts --dit <dir> everywhere it accepted a DiT file,
  for both --dump-params and the run path; every existing --dit form unchanged.

Gates (CPU, re-run post-rebase: test_minimax_h3 72/72 cases / 54497 assertions;
clean Release build of libvllm.a, test_minimax_h3 and minimax-h3-gen):
(1) index + name mapping over a synthetic 4-shard set — every tensor resolves to
the shard the index named AND to the bytes written there, a missing-from-shard
tensor throws WITH ITS NAME, and the geometry equals the single-file path field
for field; (2) real geometry without the weights — a 13-shard release declaring
the REAL 535 tensors at REAL shapes with a SPARSE payload (66.3 GB declared,
144 KB on disk) derives the SHIPPED geometry
(50 / 5376 / 56 / 128 / 14336 / 24 / 32 / 1x2x2 / 5120), and
`minimax-h3-gen --dit <dir> --dump-params` prints all 20 fields on it.

Also repairs two gates that f34e0d1 (#95) left RED on main and that block any
PR branched from it: docs/ENVIRONMENT.md now documents VT_H3_ACT_DUMP and
VT_H3_ACT_CALL (check-env-doc), and the §9 spec table that ran into the next
table without a separator now has one (check-agent-record).

Also fixes a real latent defect this row's ASan+UBSan lane exposed:
MiniMaxH3ReadSafetensorF32 read 16-bit payloads through
reinterpret_cast<const uint16_t*>, which is UB on a safetensors file whose JSON
header leaves the payload odd-aligned — the format does not require padding, and
LoadMiniMaxH3DitFromShards is the first caller to hand it such a file. Now a
byte-wise memcpy load. RED-first proven locally on the same sanitizer build:
reverting it reproduces CI's `load of misaligned address ... requires 2 byte
alignment` at the same line and exits 1; with it, test_minimax_h3 is 73/73 /
55203 under -fsanitize=address,undefined with ZERO findings. The synthetic shard
writer stays deliberately UNPADDED so the case remains covered.

Honest residuals: NO device load of the real 66.3 GB release ships here, no
measured peak RSS, and no bf16-vs-quantized render or speed number. The
bf16-vs-quant quality question is UNBLOCKED, not answered.

FOLLOWING_AGENTS_PROTOCOL
Assisted-by: Claude Opus 5 (1M context)

Co-authored-by: Ettore Di Giacinto <mudler@localai.io>